---
description: Vodite changelog
title: Vodite changelog
language: sr
version: 1.0.0
---

- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
- gh = "https://github.com/olivierlacan/keep-a-changelog"
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
- semver = "https://semver.org/"
- shields = "https://shields.io/"
- thechangelog = "http://5by5.tv/changelog/127"
- vandamme = "https://github.com/tech-angels/vandamme/"
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
- ghr = "https://help.github.com/articles/creating-releases/"
- gnustyle = "https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs"
- gnunews = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File"

.header
  .title
    %h1 Vodite Changelog
    %h2 Ne dajte prijateljima da trpaju git logove u changelogove.

  = link_to changelog do
    Verzija
    %strong= current_page.metadata[:page][:version]

  %pre.changelog= File.read("CHANGELOG.md")

.answers
  %h3#what
    %a.anchor{ href: "#what", aria_hidden: "true" }
    Šta je changelog?

  %p
    Changelog je datoteka koja sadrži uređeni hronološki
    poređani popis značajnih promena unutar svake verzije projekta.

  %h3#why
    %a.anchor{ href: "#why", aria_hidden: "true" }
    Zašto voditi changelog?

  %p
    Kako bi korisnici i saradnici detaljno videli
    značajne promjene među pojedinim izdanjima (ili verzijama)
    projekta.

  %h3#who
    %a.anchor{ href: "#who", aria_hidden: "true" }
    Kome treba changelog?

  %p
    Ljudima. Bilo da su uobičajeni korisnici ili programeri, krajnji su korisnici
    softvera ljudska bića kojima je stalo do toga od čega je sastavljen. Kada
    se softver menja, korisnici žele znati kako i zašto.

.good-practices
  %h3#how
    %a.anchor{ href: "#how", aria_hidden: "true" }
    Kako kreirati dobar changelog?

  %h4#principles
    %a.anchor{ href: "#principles", aria_hidden: "true" }
    Glavna načela

  %ul
    %li
      Changelogs služi <em> ljudima</em>, ne mašinama.
    %li
      Potrebno je stvoriti unos za svaku verziju.
    %li
      Slične promene potrebno je grupisati.
    %li
      Verzije i odeljci trebaju imati vezu.
    %li
      Poslednja verzija treba biti na prvom mestu.
    %li
      Datum izdavanja svake pojedine verzije treba biti vidljiv.
    %li
      Navesti prati li se #{link_to "Semantičko verzioniranje", semver}.

  %a.anchor{ href: "#types", aria_hidden: "true" }
  %h4#types Vrste promena

  %ul
    %li
      %code Added
      za nove funkcionalnosti.
    %li
      %code Changed
      za promene u postojećim funkcionalnostima.
    %li
      %code Deprecated
      za funkcionalnosti koje će se ukloniti u budućim verzijama.
    %li
      %code Removed
      za uklonjene funkcionalnosti.
    %li
      %code Fixed
      za ispravke bagova.
    %li
      %code Security
      za slučaj sigurnosnih propusta.

.effort

  %h3#effort
    %a.anchor{ href: "#effort", aria_hidden: "true" }
    Kako održavati changelog sa što manje napora?

  %p
    Na vrh postavite <code>Unreleased</code> sekciju gde ćete navoditi nadolazeće
    promene.

  %p To radimo iz dva razloga:

  %ul
    %li
      Korisnici mogu videti promene koje mogu očekivati u nadolazećim izdanjima
    %li
      Kod izdavanja nove verzije, moguće je <code>Unreleased</code> sekciju
      samo preimenovati u novo izdanje.

.bad-practices
  %h3#bad-practices
    %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
    Može li changelog biti loš?

  %p Naravno. Postoji nekoliko slučajeva u kojima changelog može biti beskoristan.

  %h4#log-diffs
    %a.anchor{ href: "#log-diffs", aria_hidden: "true" }
    Commit log diffovi

  %p
    Korištenje commit log diffova u svrhu changeloga nije dobra ideja:
    puni su šuma. Npr. merge commitovi, commitovi s nejasnim naslovima,
    promene u dokumentaciji i sl.

  %p
    Svrha commita je da beleži korake u razvoju izvornog koda.
    U nekim projektima se comittovi čiste, no ponekad i ne.

  %p
    Svrha unosa u changelogu je da beleži značajne razlike, a
    često kroz više commitova i jasno ih prenese krajnjem
    korisniku.

  %h4#ignoring-deprecations
    %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
    Ignorisanje uklonjenih funkcionalnosti

  %p
    Kad korisnici nadograde softver na noviju verziju, treba biti potpuno
    jasno da postoji mogućnost da će se neki deo pokvariti. Softver treba biti
    moguće nadograditi na verziju koja će navesti funkcionalnosti koje trebaju
    biti uklonjene, uklanja takve te se kasnije može nadograditi na verziju
    gde su već uklonjene.

  %p
    U najmanju ruku, potrebno je u changelogu navoditi funkcionalnosti koje će
    biti uklonjene, funkcionalnosti koje su uklonjene i promene koje će
    uticati na rad softvera (breaking change).


  %h4#confusing-dates
    %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
    Nejasni datumi

  %p
    Regionalni formati datuma variraju delom sveta, pa je često
    teško pronaći format datuma koji će odgovarati svima.
    Prednost datuma u formatu <code>2017-07-17</code> je to što je poređan
    od veće prema manjoj jedinici: godina, mesec, dan. Ovaj je format takođe
    teško zameniti s drugim regionalnim formatima, za razliku od nekih koji,
    primera radi, menjaju poziciju oznake meseca i dana.
    Iz tog razloga, a i zbog toga što je navedeni format #{link_to "ISO standard", iso},
    taj se format preporučuje za changelog unose.

  %aside
    Ali to nije sve. Pomozite u prikupljanju primera loše prakse
    = link_to "otvorivši issue", issues
    ili pull request.

.frequently-asked-questions
  %h3#frequently-asked-questions
    %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
    Česta pitanja

  %h4#standard
    %a.anchor{ href: "#standard", aria_hidden: "true" }
    Postoji li standardni changelog format?

  %p
    Zapravo ne. Postoji #{link_to "GNU changelog stilski priručnik", gnustyle},
    i #{link_to "GNU NEWS file", gnunews}
    "priručnik od dva odlomka". Nijedan nije adekvatan ni dovoljan.

  %p
    Cilj ovoga projekta
    = link_to "kvalitetniji changelog standard.", changelog
    Nastao je prikupljanjem primera dobra prakse u
    open source zajednici.

  %p
    Konstruktivna kritika, raprave i predlozi za poboljšanje
    = link_to "su dobrodošli.", issues


  %h4#filename
    %a.anchor{ href: "#filename", aria_hidden: "true" }
    Kako nazvati changelog datoteku?

  %p
    Dajemo joj naziv <code>CHANGELOG.md</code>. Neki projekti još koriste
    <code>HISTORY</code>, <code>NEWS</code> ili <code>RELEASES</code>.

  %p
    Iako može delovati da naziv changelog datoteke i nije toliko
    bitan, čemu otežavati korisnicima da dođu do informacije o promjenama?

  %h4#github-releases
    %a.anchor{ href: "#github-releases", aria_hidden: "true" }
    Šta s GitHub Releases?

  %p
    To je ozbiljna inicijativa. #{link_to "Releases", ghr} se mogu koristiti
    kako bi git oznake (npr. git oznaka <code>v1.0.0</code>) pretvorili
    u opširnije beleške o izdanju, upisujući ih ručno ili pak preuzimajući
    anotirane git oznake i pretvarajući ih u unose.

  %p
    GitHub Releases stvara statični changelog vidljiv korisnicima
    unutar GitHub repozitorijuma. Moguće ih je urediti u format koji
    bi odgovarao Vodite changelog formatu, no često je nešto opširniji.

  %p
    Trenutna GitHub releases verzija i nije baš sasvim vidljiva
    korisnicima, za razliku od uobičajenih datoteka označenih velikim slovima
    (<code>README</code>, <code>CONTRIBUTING</code>, itd.). Još je jedan
    manji problem što trenutno interfejs ne nudi poveznice na commit logove
    između izdanja.

  %h4#automatic
    %a.anchor{ href: "#automatic", aria_hidden: "true" }
    Mogu li changelogovi automatski parsirati?

  %p
    Teže, jer se koriste vrlo različiti formati, kao i nazivi datoteka.

  %p
    #{link_to "Vandamme", vandamme} je Ruby gem koji je kreirao
    Gemnasium tim i može parsirati mnoge (ali
    ne sve) changelogove projekata otvorenog koda.


  %h4#yanked
    %a.anchor{ href: "#yanked", aria_hidden: "true" }
    Šta s povučenim izdanjima?

  %p
    Povučena ili 'Yanked' izdanja su verzije koje su uklonjene zbog
    ozbiljnijeg baga ili sigurnosnog propusta. Takva se izdanja najčešće
    i ne pojavljuju u changelogu, iako bi trebala. Trebala bi biti navedena
    na sledeći način:

  %p <code>## [0.0.5] - 2014-12-13 [YANKED]</code>

  %p
    <code>[YANKED]</code> oznaka jasno je istaknuta s razlogom. Bitno je
    da ju je lako primetiti. Buduće da je okružena zagradama, takođe ju
    je lakše parsirati.


  %h4#rewrite
    %a.anchor{ href: "#rewrite", aria_hidden: "true" }
    Da li je potrebno prepravljati changelog?

  %p
    Naravno. Često postoje dobri razlozi da bismo poboljšali changelog. Ja
    često otvaram pull requestove kako bih dodao nedostajuća izdanja projektima
    otvorenog koda, koji ne održavaju changelogove.

  %p
    Moguće je, takođe da otkrijete, kako ste zaboravili navesti promenu koja
    bi uticala na rad (breaking change). U tom slučaju je, očito, vrlo bitno
    ažurirati changelog.


  %h4#contribute
    %a.anchor{ href: "#contribute", aria_hidden: "true" }
    Kako doprineti?

  %p
    Ovaj dokument nije <em>Sveto Pismo</em>; ovo je samo pažljivo
    razmotreno mišljenje, uz informacije i primere koje sam skupio.

  %p
    Razlog je tome to što želim da zajednica postigne konsenzus. Verujem,
    takođe, da je i sama rasprava bitna kao i krajnji rezultat.

  %p
    Zato, molimo <strong>#{link_to "uskočite", gh}</strong>.

.press
  %h3 Razgovori
  %p
    Gostovao sam na #{link_to "The Changelog podcastu", thechangelog}
    gde sam pokušao objasniti zašto začetnici projekata i saradnici trebaju
    brinuti o changelogovima te motivaciji iza ovog projekta.
